<!--
  ~ Copyright (C) 2011 United States Government as represented by the Administrator of the
  ~ National Aeronautics and Space Administration.
  ~ All Rights Reserved.
  -->

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
        "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
    <title>KML Parser Package</title>
</head>
<body>
<p>Provides classes for parsing KML and KMZ files and streams.</p>
<h4>How to Parse a KML or KMZ File or Stream</h4>
<ol>
    <li>
        Create a {@link gov.nasa.worldwind.ogc.kml.KMLRoot} via one of its constructors, such as {@link
        gov.nasa.worldwind.ogc.kml.KMLRoot#KMLRoot(java.io.File)}, passing the KML or KMZ source to the constructor. A
        <code>KMLRoot</code> provides access to the KML contents. The source can be either a file, an input stream or a
        URL.
    </li>
    <li>
        Call {@link gov.nasa.worldwind.ogc.kml.KMLRoot#parse(Object[])} to parse the document.
    </li>
    <li>
        The <code>KMLRoot</code> class provides accessor methods for the <code>kml</code> element of the KML file, its
        root. The content includes the element's single attribute, <i>hint</i>, and the <i>NetworkLinkControl</i> and
        <i>Feature</i> elements it may contain. Once the root is parsed, use these methods to obtain objects
        representing these elements, and use the accessor methods of those objects in turn to obtain their contents.
    </li>
    <li>
        Each KML element defined in the <a href="http://www.opengeospatial.org/standards/kml/">KML specification</a> has
        a corresponding class provided in this package. Each of those classes contains methods to obtain the element's
        contents as defined by the specification. The same is true for the other specifications KML uses: <a
            href="http://tools.ietf.org/html/rfc4287">Atom</a>, <a
            href="http://www.oasis-open.org/committees/ciq/download.html">XAL</a> and the <a
            href="http://code.google.com/apis/kml/documentation/kmlreference.html#kmlextensions"> GX extensions</a>
        defined by Google. Use these classes to obtain the contents of individual elements of the KML file.
    </li>
</ol>
The classes in this package only read and parse a KML file. Mapping them to shapes, annotations and other World Wind
objects is a separate step. World Wind provides default mappings for many KML elements, but an application is fully able
to provide its own, and in some cases is expected to.
<h4>Extending the Classes</h4>

<p>This package's classes are designed for easy behavior modification and replacement, and for straightforward additon
   of operations to be performed during parsing. See the description of {@link
   gov.nasa.worldwind.util.xml.AbstractXMLEventParser} for further information.</p>

<h4>Relative References</h4>

<p>
    Because the KML specification requires relative references within KML files to be resolved relative to the location
    of the file, a context is provided to resolve these references. The context is specific to the document type &#151;
    file, stream, KML or KMZ &#151; and is provided by the {@link gov.nasa.worldwind.ogc.kml.io.KMLDoc} interface and
    its implementing classes. It's available from the {@link gov.nasa.worldwind.ogc.kml.KMLRoot}. See the description of
    the <code>KMLDoc</code> interface for further information. </p>
</body>
</html>
